14.5 Graphical Devices

The g D (calc-graph-device) command sets the device name (or “terminal name” in GNUPLOT lingo) to be used by g p commands on this graph. It does not affect the permanent default device name. If you enter a blank name, the device name reverts to the default. Enter ‘?’ to see a list of supported devices.

With a positive numeric prefix argument, g D instead sets the default device name, used by all plots in the future which do not override it with a plain g D command. If you enter a blank line this command shows you the current default. The special name default signifies that Calc should choose x11 if the X window system is in use (as indicated by the presence of a DISPLAY environment variable), windows on MS-Windows, or otherwise dumb under GNUPLOT 3.0 and later, or postscript under GNUPLOT 2.0. This is the initial default value.

The dumb device is an interface to “dumb terminals,” i.e., terminals with no special graphics facilities. It writes a crude picture of the graph composed of characters like - and | to a buffer called ‘*Gnuplot Trail*’, which Calc then displays. The graph is made the same size as the Emacs screen, which on most dumb terminals will be 80x24 characters. The graph is displayed in an Emacs “recursive edit”; type q or C-c C-c to exit the recursive edit and return to Calc. Note that the dumb device is present only in GNUPLOT 3.0 and later versions.

The word dumb may be followed by two numbers separated by spaces. These are the desired width and height of the graph in characters. Also, the device name big is like dumb but creates a graph four times the width and height of the Emacs screen. You will then have to scroll around to view the entire graph. In the ‘*Gnuplot Trail*’ buffer, <SPC>, <DEL>, <, and > are defined to scroll by one screenful in each of the four directions.

With a negative numeric prefix argument, g D sets or displays the device name used by g P (calc-graph-print). This is initially postscript. If you don't have a PostScript printer, you may decide once again to use dumb to create a plot on any text-only printer.

The g O (calc-graph-output) command sets the name of the output file used by GNUPLOT. For some devices, notably x11 and windows, there is no output file and this information is not used. Many other “devices” are really file formats like postscript; in these cases the output in the desired format goes into the file you name with g O. Type g O stdout <RET> to set GNUPLOT to write to its standard output stream, i.e., to ‘*Gnuplot Trail*’. This is the default setting.

Another special output name is tty, which means that GNUPLOT is going to write graphics commands directly to its standard output, which you wish Emacs to pass through to your terminal. Tektronix graphics terminals, among other devices, operate this way. Calc does this by telling GNUPLOT to write to a temporary file, then running a sub-shell executing the command ‘cat tempfile >/dev/tty’. On typical Unix systems, this will copy the temporary file directly to the terminal, bypassing Emacs entirely. You will have to type C-l to Emacs afterwards to refresh the screen.

Once again, g O with a positive or negative prefix argument sets the default or printer output file names, respectively. In each case you can specify auto, which causes Calc to invent a temporary file name for each g p (or g P) command. This temporary file will be deleted once it has been displayed or printed. If the output file name is not auto, the file is not automatically deleted.

The default and printer devices and output files can be saved permanently by the m m (calc-save-modes) command. The default number of data points (see g N) and the X geometry (see g X) are also saved. Other graph information is not saved; you can save a graph's configuration simply by saving the contents of the ‘*Gnuplot Commands*’ buffer.

You may wish to configure the default and printer devices and output files for the whole system. The relevant Lisp variables are calc-gnuplot-default-device and -output, and calc-gnuplot-print-device and -output. The output file names must be either strings as described above, or Lisp expressions which are evaluated on the fly to get the output file names.

Other important Lisp variables are calc-gnuplot-plot-command and calc-gnuplot-print-command, which give the system commands to display or print the output of GNUPLOT, respectively. These may be nil if no command is necessary, or strings which can include ‘%s’ to signify the name of the file to be displayed or printed. Or, these variables may contain Lisp expressions which are evaluated to display or print the output. These variables are customizable (see Customizing Calc).

The g x (calc-graph-display) command lets you specify on which X window system display your graphs should be drawn. Enter a blank line to see the current display name. This command has no effect unless the current device is x11.

The g X (calc-graph-geometry) command is a similar command for specifying the position and size of the X window. The normal value is default, which generally means your window manager will let you place the window interactively. Entering ‘800x500+0+0’ would create an 800-by-500 pixel window in the upper-left corner of the screen. This command has no effect if the current device is windows.

The buffer called ‘*Gnuplot Trail*’ holds a transcript of the session with GNUPLOT. This shows the commands Calc has “typed” to GNUPLOT and the responses it has received. Calc tries to notice when an error message has appeared here and display the buffer for you when this happens. You can check this buffer yourself if you suspect something has gone wrong¹.

The g C (calc-graph-command) command prompts you to enter any line of text, then simply sends that line to the current GNUPLOT process. The ‘*Gnuplot Trail*’ buffer looks deceptively like a Shell buffer but you can't type commands in it yourself. Instead, you must use g C for this purpose.

The g v (calc-graph-view-commands) and g V (calc-graph-view-trail) commands display the ‘*Gnuplot Commands*’ and ‘*Gnuplot Trail*’ buffers, respectively, in another window. This happens automatically when Calc thinks there is something you will want to see in either of these buffers. If you type g v or g V when the relevant buffer is already displayed, the buffer is hidden again. (Note that on MS-Windows, the ‘*Gnuplot Trail*’ buffer will usually show nothing of interest, because GNUPLOT's responses are not communicated back to Calc.)

One reason to use g v is to add your own commands to the ‘*Gnuplot Commands*’ buffer. Press g v, then use C-x o to switch into that window. For example, GNUPLOT has ‘set label’ and ‘set arrow’ commands that allow you to annotate your plots. Since Calc doesn't understand these commands, you have to add them to the ‘*Gnuplot Commands*’ buffer yourself, then use g p to replot using these new commands. Note that your commands must appear before the plot command. To get help on any GNUPLOT feature, type, e.g., g C help set label. You may have to type g C <RET> a few times to clear the “press return for more” or “subtopic of ...” requests. Note that Calc always sends commands (like ‘set nolabel’) to reset all plotting parameters to the defaults before each plot, so to delete a label all you need to do is delete the ‘set label’ line you added (or comment it out with ‘#’) and then replot with g p.

You can use g q (calc-graph-quit) to kill the GNUPLOT process that is running. The next graphing command you give will start a fresh GNUPLOT process. The word ‘Graph’ appears in the Calc window's mode line whenever a GNUPLOT process is currently running. The GNUPLOT process is automatically killed when you exit Emacs if you haven't killed it manually by then.

The g K (calc-graph-kill) command is like g q except that it also views the ‘*Gnuplot Trail*’ buffer so that you can see the process being killed. This is better if you are killing GNUPLOT because you think it has gotten stuck.